Skip to main content
POST
/
public
/
v1
/
toptimize
/
forecasting
/
inventory
[BETA] Inventory-level Forecasts
curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/inventory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inventory": [
    {
      "inventoryType": "category",
      "inventoryValue": "<string>"
    }
  ],
  "timeWindow": 2
}'
[
  {
    "inventoryType": "category",
    "inventoryValue": "electronics",
    "dailyForecasts": [
      {
        "forecastDate": "2025-01-15",
        "metrics": [
          {
            "metricName": "total_auctions",
            "values": {
              "forecastValue": 12500,
              "forecastIntervalMin": 11800,
              "forecastIntervalMax": 13200
            }
          },
          {
            "metricName": "total_slots",
            "values": {
              "forecastValue": 25000,
              "forecastIntervalMin": 23500,
              "forecastIntervalMax": 26500
            }
          },
          {
            "metricName": "total_winners",
            "values": {
              "forecastValue": 8750,
              "forecastIntervalMin": 8200,
              "forecastIntervalMax": 9300
            }
          },
          {
            "metricName": "total_impressions",
            "values": {
              "forecastValue": 18750,
              "forecastIntervalMin": 17600,
              "forecastIntervalMax": 19900
            }
          },
          {
            "metricName": "total_clicks",
            "values": {
              "forecastValue": 3750,
              "forecastIntervalMin": 3500,
              "forecastIntervalMax": 4000
            }
          },
          {
            "metricName": "avg_cpc",
            "values": {
              "forecastValue": 2.85,
              "forecastIntervalMin": 2.7,
              "forecastIntervalMax": 3
            }
          },
          {
            "metricName": "avg_ctr",
            "values": {
              "forecastValue": 0.2,
              "forecastIntervalMin": 0.18,
              "forecastIntervalMax": 0.22
            }
          },
          {
            "metricName": "slot_occupancy",
            "values": {
              "forecastValue": 0.7,
              "forecastIntervalMin": 0.65,
              "forecastIntervalMax": 0.75
            }
          },
          {
            "metricName": "total_capacity",
            "values": {
              "forecastValue": 125000,
              "forecastIntervalMin": 118000,
              "forecastIntervalMax": 132000
            }
          },
          {
            "metricName": "occupied_capacity",
            "values": {
              "forecastValue": 87500,
              "forecastIntervalMin": 82000,
              "forecastIntervalMax": 93000
            }
          }
        ]
      }
    ]
  },
  {
    "inventoryType": "search",
    "inventoryValue": "smartphone",
    "dailyForecasts": [
      {
        "forecastDate": "2025-01-15",
        "metrics": [
          {
            "metricName": "total_auctions",
            "values": {
              "forecastValue": 12500,
              "forecastIntervalMin": 11800,
              "forecastIntervalMax": 13200
            }
          },
          {
            "metricName": "total_slots",
            "values": {
              "forecastValue": 25000,
              "forecastIntervalMin": 23500,
              "forecastIntervalMax": 26500
            }
          },
          {
            "metricName": "total_winners",
            "values": {
              "forecastValue": 8750,
              "forecastIntervalMin": 8200,
              "forecastIntervalMax": 9300
            }
          },
          {
            "metricName": "total_impressions",
            "values": {
              "forecastValue": 18750,
              "forecastIntervalMin": 17600,
              "forecastIntervalMax": 19900
            }
          },
          {
            "metricName": "total_clicks",
            "values": {
              "forecastValue": 3750,
              "forecastIntervalMin": 3500,
              "forecastIntervalMax": 4000
            }
          },
          {
            "metricName": "avg_cpc",
            "values": {
              "forecastValue": 2.85,
              "forecastIntervalMin": 2.7,
              "forecastIntervalMax": 3
            }
          },
          {
            "metricName": "avg_ctr",
            "values": {
              "forecastValue": 0.2,
              "forecastIntervalMin": 0.18,
              "forecastIntervalMax": 0.22
            }
          },
          {
            "metricName": "slot_occupancy",
            "values": {
              "forecastValue": 0.7,
              "forecastIntervalMin": 0.65,
              "forecastIntervalMax": 0.75
            }
          },
          {
            "metricName": "total_capacity",
            "values": {
              "forecastValue": 125000,
              "forecastIntervalMin": 118000,
              "forecastIntervalMax": 132000
            }
          },
          {
            "metricName": "occupied_capacity",
            "values": {
              "forecastValue": 87500,
              "forecastIntervalMin": 82000,
              "forecastIntervalMax": 93000
            }
          }
        ]
      }
    ]
  }
]

Authorizations

​
Authorization
string
header
required

A valid API key generated in Topsort's UI.

Body

application/json

Request model for batch inventory forecasts.

​
inventory
InventoryItem · object[]
required

List of inventory type and value combinations to forecast

​
timeWindow
integer | null
default:7

Number of days in the future to retrieve forecasts for.

Required range: x >= 1

Response

Successful Response

​
inventoryType
enum<string>
required

The type of inventory

Available options:
category,
search
​
inventoryValue
string
required

The value of the inventory

​
dailyForecasts
DailyForecast · object[]
required

List of daily forecasts for this inventory